Build iOS part tasks in slices so the next mutate() does not wait - #70

What was wrong

On iOS, a chunked mutate() builds a part file and a task for every part. Since 11.0.0 it did all of this in one block on the coordinator queue. For a 2 GiB capture in 20 MiB parts that is 103 part copies (2 GiB read and 2 GiB written), 103 task map writes with fsync, and 103 task creations.

Diana calls mutate() on the capture file and then at once on its metadata. The metadata mutate() waited behind the whole build, and the 10 s enqueue timeout rejected it (Sentry DIANA-11QD, 2.5% of users on every v11 build).

Also, the 11.0.1 CHANGELOG said the task map was written once per batch. It was written once per part task.

What changes

sequenceDiagram
  participant JS
  participant Q as Coordinator queue
  JS->>Q: mutate(file)
  Q-->>JS: resolve
  Q->>Q: slice 1 (about 32 MiB of parts)
  JS->>Q: mutate(metadata)
  Q-->>JS: resolve (waited for slice 1 only)
  Q->>Q: slice 2, slice 3, ... until every part has a task

• refill builds the parts in slices of about 32 MiB (two 20 MiB parts). Each slice is its own block on the queue. Other calls run between two slices, so a mutate() waits for at most one slice per chunked upload that is building its parts.
• One continuation per entry (queuedSlices). Each slice runs refill again: it checks the entry again and computes "pending minus in flight" again. So a part never gets two tasks, and a cancel, pause, replace or expiry between two slices stops the build. Each slice block also refreshes the row's nextAttemptAt.
• A slice creates its tasks suspended, writes their task map entries in one write, then resumes them. Transport.upload no longer resumes the task. The rule "task map entry before resume" stays.
• Reconcile resumes every task it adopts, part and simple, at its end (after settles and pause gates, so a task they stopped sends nothing). So a crash between a slice's task map write and its resumes does not leave suspended tasks that never send.
• Replacing background-created part tasks when the app becomes active also works one slice at a time.
  • Each old task is cancelled in the slice that replaces it, so a part keeps its old task until its new one exists, unless that slice's build fails. Then the part waits for the refill after the backoff.
  • Every slice checks again that the old task is live, has sent no body byte and has no response. A task the daemon started while it waited is kept.
  • Replacing stops if the app leaves the foreground again. A replace slice with nothing left to replace continues the refill plan.
  • A running entry past its expiresAt now settles expired at that point instead of getting new tasks (CHANGELOG line).
• The background completion handler waits until no slice is queued, in the relaunch reconcile and in urlSessionDidFinishEvents. It stops waiting for slices when less than 5 s of background time is left (UIApplication.backgroundTimeRemaining, read on main and passed to the coordinator as a closure). Grace waits are never cut short.
• os_signpost intervals for each enqueue, issue, part slice and replace slice (subsystem ai.openspace.rnbgupload, Points of Interest). Entry ids are logged as public, so they must stay free of user content.
• Task creation stays in the foreground: the slices run one after the other, right after mutate(). This is not the v10 lazy window. A slice that runs after the app leaves the foreground tags its tasks as background tasks, and the next activation replaces them, as for any background-created task.

No API change. mutate() resolves at the same point as before.

Memory

This PR does not fix the out-of-memory crashes on this path (DIANA-3QVM in enqueueParts, DIANA-3S18 in TaskMap.write). It changes two things that touch them:

• Task map writes per 2 GiB plan go from 103 to 52 (one per slice of two 20 MiB parts). Each write still encodes the whole map.
• The part copy wraps each 1 MiB read in autoreleasepool, so each read buffer is freed before the next read. The copy runs inside store.queue.sync on the caller's thread, so a queue-level autoreleaseFrequency would not cover it.

Where to look

• ios/ChunkedCoordinator.swift: refill, refillNextSlice, replace and replaceSlice, runnable, and the task map batch in enqueueParts.
• ios/QueueCoordinator+Reconcile.swift: whenIdle, releaseIfIdle, the wake time check, and resume() on adopted tasks.
• ios/RNBackgroundUpload.swift: urlSessionDidFinishEvents holds the handler until the coordinator is idle; the backgroundTimeRemaining closure.
• ios/QueueStore.swift: the autoreleasepool in the part copy.
• ios/Transport.swift, ios/TaskMap.swift, ios/Signpost.swift.
• Example app (first commit): "Enqueue latency x7" and the harness.chunked20 kind.

What only a device can show

• Enqueue latency. On an iPhone 11 or similar older device, with about 4 GiB free for each run plus 2 GiB for the kept source, run the example app's "Enqueue latency x7" (example README, iOS step 19). It calls resume(), then runs 7 times: copy a 2 GiB source, mutate() it in 103 parts of 20 MiB, then at once mutate() a small JSON request, both on the server's slow mode. It logs nextMs, how long the second mutate() waits, and the median and maximum. Compare a build of commit 56c51c9 (the harness on top of master's native code) with a build of this PR's tip, on the same device. Target for the tip: median nextMs under 500 ms, maximum under 2 s.
• backgroundTimeRemaining in a background-session relaunch. Look at the value it reports during a handleEventsForBackgroundURLSession relaunch (log it, or break in the debugger). The 5 s cap depends on it: if iOS reports no limit there, the cap never fires.

Test plan

• cd ios && swift test: 265 tests, 0 failures, 1 skipped (the perf test). Before this PR: 235.
• RNBGU_PERF=1 swift test --filter ChunkedPerfTests: 200 MiB plan, 10 parts of 20 MiB, real part files, fake sessions. Next enqueue median 17.4 ms with slices, 67.0 ms with the whole plan in one block (on a Mac; fsync dominates there). It does not include nsurlsessiond.
• yarn lint:ci, yarn typecheck, yarn test (194 tests).
• Example app yarn test: 5 tests (1 new, for the latency button).
• RNBackgroundUpload.swift typechecks against the iOS 15.1 simulator SDK (with stubs for the React symbols).

🤖 Generated with Claude Code